src/components/StructuredData.astro-7-28 (1)

7-28: 🛠️ Refactor suggestion | 🟠 Major

Props interface must be named Props for Astro to infer Astro.props types.

Astro resolves the component's prop types by looking for an interface (or type alias) literally named Props in the frontmatter. The current name StructuredDataProps means Astro.props and its destructuring at line 30 are effectively any, so callers get no type-checking or IDE autocompletion.

♻️ Rename to `Props`

-interface StructuredDataProps {
+interface Props {
   type: 'WebPage' | 'Article' | 'BlogPosting' | 'Organization';

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/StructuredData.astro` around lines 7 - 28, The interface
currently named StructuredDataProps prevents Astro from inferring Astro.props;
rename the interface to Props so Astro can pick up the types and enable proper
type-checking/autocomplete for Astro.props and the component's destructured
props (the interface fields like type, data, canonicalUrl, and nested
author/publisher/image fields should remain unchanged).

src/components/StructuredData.astro-33-38 (1)

33-38: ⚠️ Potential issue | 🟠 Major

data.url silently overrides canonicalUrl — spread order is semantically backwards.

Because ...data appears after url: canonicalUrl, any caller that passes data.url will overwrite the canonical URL. The prop name canonicalUrl implies it should be the authoritative url value in the output. Either give canonicalUrl precedence by spreading data first, or remove url from the data interface to avoid the ambiguity entirely.

🛠️ Option A — give `canonicalUrl` precedence (swap spread order)

 const structuredData = {
   '@context': 'https://schema.org',
   '@type': type,
+  ...data,
   url: canonicalUrl,
-  ...data,
 };

🛠️ Option B — remove `url` from `data` to eliminate the conflict

   data: {
     name?: string;
     headline?: string;
     description: string;
-    url?: string;
     datePublished?: string;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/StructuredData.astro` around lines 33 - 38, The constructed
object structuredData currently places ...data after url: canonicalUrl so any
data.url will override the canonicalUrl; fix by giving canonicalUrl
precedence—spread data first (i.e., ...data before url) so url: canonicalUrl
wins—or alternatively remove url from the data prop/interface so callers cannot
pass data.url; update the structuredData creation accordingly (referencing
structuredData, canonicalUrl, data, and url).

src/content/docs/blog/2026-01-28-利用-worker-threads-优化-vite-构建性能的实战.mdx-207-207 (1)

207-207: ⚠️ Potential issue | 🟠 Major

new Worker('./worker.ts') won't work natively — Node.js Worker threads require compiled JS.

The Node.js worker_threads Worker constructor accepts a .js file (or a data URL), not a .ts source file. Readers who copy this verbatim will get a runtime error. The article should note that the TypeScript file must first be compiled (e.g., via tsc, esbuild, or using tsx/ts-node with a loader), or show the correct approach for a TypeScript-first project (e.g., passing a compiled output path or using a bundler-aware workaround).

A common pattern in Vite plugins is to use new URL('./worker.js', import.meta.url) pointing at the compiled output, or to inline the worker via a bundler plugin.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/blog/2026-01-28-利用-worker-threads-优化-vite-构建性能的实战.mdx` at
line 207, The example uses new Worker('./worker.ts') which fails at runtime
because Node's worker_threads expects compiled JS or a data URL; update the
example and text to show a valid approach: explain that worker.ts must be
compiled and demonstrate creating the Worker with the compiled output (e.g., new
Worker(new URL('./worker.js', import.meta.url)) or a bundler/runtime toolchain
like tsc/esbuild/tsx/ts-node) and mention alternatives (data URL or bundler
inlining) so readers know to point Worker at a .js bundle or use a loader rather
than the raw .ts file.

src/content/docs/blog/2026-01-28-利用-worker-threads-优化-vite-构建性能的实战.mdx-185-242 (1)

185-242: ⚠️ Potential issue | 🟠 Major

WorkerPool example has two bugs that would prevent it from working.

Bug 1 — activeWorkers is never declared. The class body only declares workers and taskQueue, but this.activeWorkers is used as a Map<Worker, ObfuscationTask> in createWorker, runTask, and dispatchTask. Any reader who copies this snippet will get a TypeError: Cannot read properties of undefined at runtime.

Bug 2 — runTask promises never resolve. The worker.on('message', ...) handler receives the worker's result but never calls job.resolve(result). Every caller of runTask() will hang indefinitely. The handler needs to look up the in-flight job for that worker and resolve it.

🐛 Proposed fix for both bugs

 export class WorkerPool {
   private workers: Worker[] = []
+  private activeWorkers = new Map<Worker, { task: ObfuscationTask; resolve: (r: ObfuscationResult) => void; reject: (e: Error) => void }>()
   private taskQueue: Array<{
     task: ObfuscationTask
     resolve: (result: ObfuscationResult) => void
     reject: (error: Error) => void
   }> = []

   // ...

   private createWorker() {
     const worker = new Worker('./worker.ts')

     worker.on('message', (result: ObfuscationResult) => {
+      // Resolve the in-flight job for this worker
+      const job = this.activeWorkers.get(worker)
+      if (job) job.resolve(result)
+
       const nextTask = this.taskQueue.shift()
       if (nextTask) {
         this.dispatchTask(worker, nextTask)
       } else {
         this.activeWorkers.delete(worker)
       }
     })

     this.workers.push(worker)
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/blog/2026-01-28-利用-worker-threads-优化-vite-构建性能的实战.mdx`
around lines 185 - 242, The WorkerPool class is missing the activeWorkers map
and the worker message handler never resolves the corresponding promise; add a
private activeWorkers: Map<Worker, ObfuscationTask> (or Map<Worker,
{task:ObfuscationTask, resolve, reject}>) to the WorkerPool class, initialize it
in the constructor, and update createWorker, runTask, and dispatchTask to use
that map; in createWorker's worker.on('message', (result) => { ... }) lookup the
in-flight job from activeWorkers for that worker, call its resolve(result) (or
resolve/reject on error), remove the worker from activeWorkers, and then pull
the next task from taskQueue and dispatch it so promises returned by runTask
actually resolve.

src/content/docs/related-software-installation/postgresql/install-on-windows.md.backup-1-158 (1)

1-158: ⚠️ Potential issue | 🟠 Major

Remove the .backup file from version control.

Backup files (.md.backup) are development artifacts that should not be tracked in git. Astro will never process this file (the .backup extension is not a recognized content format), so it contributes dead content to the repo. It also contains stale image paths (/img/install-postgres-windows/…) that diverge from the canonical .mdx counterpart (../../img/installation/install-postgres-windows/…), making it a source of confusion.

Add the extension to .gitignore and delete the file from the tree:

🗑️ Suggested cleanup

# .gitignore
+*.backup

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/content/docs/related-software-installation/postgresql/install-on-windows.md.backup`
around lines 1 - 158, Remove the tracked backup file
src/content/docs/related-software-installation/postgresql/install-on-windows.md.backup
from the repository (git rm --cached or git rm) and commit the deletion, and add
a rule to .gitignore to ignore *.backup (or specifically
install-on-windows.md.backup) so future backups aren’t committed; ensure there
are no required changes to the canonical Markdown/MDX source (e.g., the real
install-on-windows.md/.mdx) before deleting and include a short commit message
like "chore: remove .backup dev artifact and ignore *.backup".

src/content/docs/blog/2026-01-22-github-issues-集成.mdx-113-119 (1)

113-119: ⚠️ Potential issue | 🟠 Major

Security section misleadingly omits XSS risk of localStorage token storage.

Line 118 states that Same-Origin Policy (SOP) ensures only HagiCode scripts can read the token. This is inaccurate in a relevant threat model: SOP only prevents cross-origin access. Any script injected into the same origin via XSS can freely read localStorage and exfiltrate the GitHub token — potentially giving an attacker full repo write access.

The section concludes (line 328) that "Token 不经过服务器数据库，降低了泄露风险" as a pure security gain, but trades a server-side DB leak risk for a client-side XSS risk. Readers implementing this pattern should be aware of mitigations such as:

• Clearing the token on tab/session close (sessionStorage instead of localStorage).
• Using a short-lived token with minimal scopes (see the scope comment below).
• Ensuring a strong Content Security Policy (CSP) to reduce XSS attack surface.

Consider adding a "注意事项" (caveats) paragraph about XSS to avoid giving readers a false sense of security.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/blog/2026-01-22-github-issues-集成.mdx` around lines 113 -
119, Update the "安全设计" section to remove the misleading claim that Same-Origin
Policy (SOP) alone prevents token access and add a "注意事项" cave述 explicitly
warning that any script running in the same origin (e.g., via XSS) can read
localStorage and exfiltrate tokens; in the token storage bullet (the one that
currently states "Token 仅存储在浏览器的 `localStorage` 中") change the wording to
acknowledge XSS risk and add recommended mitigations: prefer sessionStorage for
session-scoped tokens or clear tokens on tab close, use short-lived tokens with
minimal scopes, and enforce a strong Content Security Policy (CSP); keep the
rest of the security bullets intact but ensure the final sentence about reduced
DB risk is balanced by this XSS caveat.

src/content/docs/blog/2026-01-22-github-issues-集成.mdx-226-256 (1)

226-256: ⚠️ Potential issue | 🟠 Major

Missing Content-Type header and outdated Accept header in GitHub API requests.

The githubApi function injects only Authorization and Accept headers, but POST requests sending JSON require explicit Content-Type: application/json. Without it, the GitHub API may reject the request with 415 Unsupported Media Type. The function also uses the outdated application/vnd.github.v3+json Accept header format; the current recommendation is application/vnd.github+json. Additionally, GitHub recommends explicitly pinning the API version via the X-GitHub-Api-Version: 2022-11-28 header rather than relying on server defaults.

Proposed fix

 async function githubApi<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
   const token = localStorage.getItem('gh_token');
   if (!token) throw new Error('Not connected to GitHub');
   
   const response = await fetch(`${GITHUB_API_BASE}${endpoint}`, {
     ...options,
     headers: {
       ...options.headers,
       Authorization: `Bearer ${token}`,
-      Accept: 'application/vnd.github.v3+json', // 指定 API 版本
+      'Accept': 'application/vnd.github+json',
+      'Content-Type': 'application/json',
+      'X-GitHub-Api-Version': '2022-11-28',
     },
   });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/blog/2026-01-22-github-issues-集成.mdx` around lines 226 -
256, The githubApi function currently sets Authorization and an outdated Accept
header and misses Content-Type for JSON bodies; update githubApi to merge
headers from options.headers and: 1) replace Accept value with
"application/vnd.github+json", 2) add "X-GitHub-Api-Version": "2022-11-28", and
3) when options.method is POST/PUT/PATCH (or when options.body is present and a
stringified JSON is used by createIssue), ensure "Content-Type":
"application/json" is set (without overwriting any explicit header provided by
the caller); keep these changes localized to the githubApi function used by
createIssue.

src/components/StarlightHead.astro-13-14 (1)

13-14: ⚠️ Potential issue | 🟠 Major

Astro.site is undefined when site is not configured — new URL(pathname, undefined) throws at build time.

Astro's site property returns a URL | undefined and is undefined if no site value is set in astro.config.*. Passing undefined as the base to new URL() throws a TypeError, crashing every page render.

🛡️ Proposed fix — guard against undefined `Astro.site`

-const url = new URL(Astro.url.pathname, Astro.site);
-const canonicalUrl = url.href;
+const canonicalUrl = Astro.site
+  ? new URL(Astro.url.pathname, Astro.site).href
+  : Astro.url.href;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/StarlightHead.astro` around lines 13 - 14, Astro.site can be
undefined so calling new URL(Astro.url.pathname, Astro.site) will throw; update
the logic around Astro.url.pathname/ Ast ro.site to guard against undefined by
only constructing the URL when Astro.site is present (use Astro.site as the base
for new URL) and otherwise derive canonicalUrl from Astro.url.pathname (or a
safe fallback string) — modify the code that assigns url/canonicalUrl (the new
URL call and the const canonicalUrl) to check Astro.site first and produce a
safe string when it's undefined.

src/components/StarlightHead.astro-29-29 (1)

29-29: ⚠️ Potential issue | 🟠 Major

Change canonicalURL to canonical in the SEO component props.

The astro-seo library expects the prop name canonical, not canonicalURL. Using the wrong prop name will prevent the canonical <link> tag from being emitted, causing the library to silently fall back to Astro.url.href.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/StarlightHead.astro` at line 29, In the SEO component usage
(the SEO element in StarlightHead.astro) replace the incorrect prop name
canonicalURL with canonical so the library emits the canonical <link>; e.g.,
change canonicalURL={canonicalUrl} to canonical={canonicalUrl} and verify the
canonicalUrl variable is defined/available in the component scope (adjust the
variable name if needed).

package.json-21-22 (1)

21-22: ⚠️ Potential issue | 🟠 Major

Move playwright and @types/* to devDependencies.

playwright, @types/react, and @types/react-dom are build/test-time concerns that should not inflate production installs. playwright alone adds hundreds of MB.

♻️ Proposed fix

   "dependencies": {
     "@astrojs/mdx": "4.3.13",
     "@astrojs/partytown": "^2.1.4",
     "@astrojs/react": "^4.4.2",
     "@astrojs/sitemap": "^3.7.0",
     "@astrojs/starlight": "^0.37.4",
-    "@types/react": "^19.2.13",
-    "@types/react-dom": "^19.2.3",
     "astro": "^5.6.1",
     ...
-    "playwright": "^1.58.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     ...
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3",
+    "playwright": "^1.58.2"
   }

Also applies to: 28-30

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@package.json` around lines 21 - 22, Dependencies list currently includes
test/build-only packages (playwright, `@types/react`, `@types/react-dom` and other
`@types` entries at 28-30); move these entries out of "dependencies" and into
"devDependencies" in package.json so production installs don't include
them—either cut the keys "playwright", "@types/react", "@types/react-dom" (and
the other `@types` entries referenced) from the dependencies object and paste them
under devDependencies, or run package manager commands like npm install
--save-dev playwright `@types/react` `@types/react-dom` to update package.json
accordingly.

package.json-24-24 (1)

24-24: ⚠️ Potential issue | 🟠 Major

Pin astro-link-validator to a specific tag to get deterministic installs.

The package itself recommends npm install github:rodgtr1/astro-link-validator#v1.0.0 to pin to a specific version. Without a tag, every fresh npm install resolves to whatever is on the default branch at that moment, making builds non-deterministic. The package's author notes it will eventually be published to npm for a cleaner update experience. Additionally, a link-validation tool is only needed at build time and should be in devDependencies.

♻️ Proposed fix

-    "astro-link-validator": "github:rodgtr1/astro-link-validator",
+    "astro-link-validator": "github:rodgtr1/astro-link-validator#v1.0.0",

And move it to devDependencies.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@package.json` at line 24, Update package.json so the GitHub dependency
"astro-link-validator" is pinned to a specific tag (e.g.,
github:rodgtr1/astro-link-validator#v1.0.0) and move that entry from
"dependencies" to "devDependencies"; locate the current "astro-link-validator"
entry in package.json and replace the value with the tagged ref and relocate the
key into the devDependencies object to ensure deterministic, build-time-only
installs.

package.json-33-33 (1)

33-33: ⚠️ Potential issue | 🟠 Major

Update rehype-raw to align with @astrojs/mdx dependencies.

The project declares rehype-raw@^3.0.0, but @astrojs/mdx@4.3.13 (a direct dependency) requires rehype-raw@^7.0.0. This version mismatch causes npm to install both versions: 3.0.0 at the root and 7.0.0 nested under @astrojs/mdx and @astrojs/markdown-remark. Version duplication can cause type conflicts and runtime errors during the rehype transform pipeline.

♻️ Proposed fix

-    "rehype-raw": "^3.0.0",
+    "rehype-raw": "^7.0.0",

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@package.json` at line 33, The project-level dependency "rehype-raw" is pinned
to ^3.0.0 which conflicts with `@astrojs/mdx`@4.3.13's requirement of
rehype-raw@^7.0.0; update the "rehype-raw" entry in package.json to ^7.0.0 (or a
range compatible with `@astrojs/mdx`) so only one major version is installed, then
regenerate the lockfile and reinstall (e.g., run npm install or yarn install) to
ensure the lockfile and node_modules reflect the single compatible version.

src/content/docs/quick-start/proposal-session.md.backup-1-417 (1)

1-417: ⚠️ Potential issue | 🟠 Major

Remove this backup file from the repository.

proposal-session.md.backup is a copy of proposal-session.mdx (identical content with the older absolute image paths). It won't be processed by Astro's docsLoader() but it pollutes the content directory and may confuse contributors about which file is authoritative. Delete it and, if needed, preserve it locally or reference the Git history.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/quick-start/proposal-session.md.backup` around lines 1 -
417, The file proposal-session.md.backup is an outdated duplicate of
proposal-session.mdx that pollutes the docs and isn't processed by Astro; delete
proposal-session.md.backup from the repo (remove the backup file entirely) and
ensure any needed history is kept via git (or local backup) instead of keeping
the .backup copy; confirm that all references and images still point to the
canonical proposal-session.mdx after deletion.

src/content/docs/quick-start/proposal-session.mdx-364-382 (1)

364-382: ⚠️ Potential issue | 🟠 Major

:::重要提示 is not a valid Starlight admonition type — the callout will not render with any styling.

Starlight aside blocks "can be of type note, tip, caution or danger." The custom string 重要提示 is unrecognized and the block will render as unstyled plain text, causing the important instruction about committing archival planning files to lose all visual emphasis.

Use a valid type and pass the Chinese label as a custom title:

🐛 Proposed fix

-:::重要提示
+:::caution[重要提示]
 **提交归档的规划文件**
 ...
 :::

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/quick-start/proposal-session.mdx` around lines 364 - 382,
The admonition currently uses an invalid Starlight type `:::重要提示`; replace that
block opener with a valid Starlight admonition type (one of `note`, `tip`,
`caution`, or `danger`) and pass the Chinese label as the custom title so it
renders with styling — e.g., change `:::重要提示` to `:::tip 重要提示` (or `:::note
重要提示`) while keeping the block content (the guidance about committing
proposal.md, tasks.md, design.md, specs/) unchanged so the callout renders
correctly; update the matching closing `:::` if present.

src/components/ClarityDebug.astro-5-5 (1)

5-5: ⚠️ Potential issue | 🟠 Major

CLARITY_DEBUG is not accessible via import.meta.env without the VITE_ prefix.

In Astro/Vite, only environment variables prefixed with VITE_ (or PUBLIC_ in Astro) are exposed through import.meta.env. import.meta.env.CLARITY_DEBUG will always be undefined. The AI summary and the sibling BaiduAnalytics.astro component both use the VITE_ prefix pattern.

🐛 Proposed fix

-const clarityDebug = import.meta.env.CLARITY_DEBUG;
+const clarityDebug = import.meta.env.VITE_CLARITY_DEBUG;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/ClarityDebug.astro` at line 5, Replace the non-exposed env
access in ClarityDebug.astro: the constant clarityDebug is currently reading
import.meta.env.CLARITY_DEBUG (which is undefined in Vite/Astro); switch it to
read the exposed variable import.meta.env.VITE_CLARITY_DEBUG (or PUBLIC_ prefix
if you intend a public var) and update any downstream usage to tolerate
string/undefined (e.g., parse/boolean-if-needed) so the component behaves the
same when the env var is absent; specifically modify the declaration of
clarityDebug in ClarityDebug.astro to reference VITE_CLARITY_DEBUG and ensure
any conditional checks against clarityDebug remain correct.

src/content/docs/installation/desktop.mdx.backup-1-292 (1)

1-292: 🛠️ Refactor suggestion | 🟠 Major

Backup file should not be committed to the repository.

desktop.mdx.backup appears to be a working copy backup alongside the actual desktop.mdx file. Committing backup files adds clutter and risks confusion about which version is canonical. Consider adding *.backup to .gitignore and removing this file from the PR.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/installation/desktop.mdx.backup` around lines 1 - 292, The
PR includes a backup file desktop.mdx.backup that should not be committed;
remove the file from the branch (delete desktop.mdx.backup), add a global ignore
rule like *.backup to .gitignore (or add desktop.mdx.backup to .gitignore if you
prefer), commit the .gitignore change, and ensure the deleted backup is removed
from the PR diff (use git rm --cached if you need to stop tracking an already
committed backup before committing the .gitignore update).

.github/workflows/version-monitor.yml-65-65 (1)

65-65: ⚠️ Potential issue | 🟠 Major

Potential command injection via unsanitized new_version in shell contexts.

steps.monitor.outputs.new_version originates from an external HTTP response (the version source URL). If that source is ever compromised, the version string is interpolated directly into shell commands (branch names, commit messages, git push, etc.) via ${{ ... }} expression expansion, which happens before the shell runs. A malicious version string (e.g., containing $(evil) or backticks) could execute arbitrary commands.

Consider sanitizing or validating the version string early in the workflow (e.g., assert it matches a semver regex) before using it in subsequent steps:

🛡️ Example validation step

+     - name: Validate version format
+       if: steps.monitor.outputs.update_needed == 'true'
+       run: |
+         VERSION="${{ steps.monitor.outputs.new_version }}"
+         if ! echo "$VERSION" | grep -Pq '^\d+\.\d+\.\d+(-[\w.]+)?$'; then
+           echo "::error::Invalid version format: $VERSION"
+           exit 1
+         fi

Also applies to: 78-78, 86-86, 91-92, 149-149

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/version-monitor.yml at line 65, The workflow uses
steps.monitor.outputs.new_version directly in shell-interpolated strings (e.g.,
BRANCH_NAME="version-update-${{ steps.monitor.outputs.new_version }}", commit
messages, git push), which risks command injection; add an early
validation/sanitization step that asserts steps.monitor.outputs.new_version
matches a strict semver regex (or otherwise strips/escapes non-alphanumeric,
dot, hyphen characters) and set a new output like validated_version or
sanitized_version from that step; then replace all occurrences of
steps.monitor.outputs.new_version (used in BRANCH_NAME, commit messages, git
commands referenced in the diff) with the validated_version/sanitized_version to
ensure only safe characters reach shell contexts and fail the job if validation
does not pass.

shared/src/desktop-context.tsx-147-165 (1)

147-165: ⚠️ Potential issue | 🟠 Major

Unhandled promise rejection in the optimization path.

The .then() call on Line 148 has no .catch() handler. If getDesktopVersionData() rejects, this results in an unhandled promise rejection, which in React strict mode or Node environments could crash the app or produce console warnings. The loadData function (Lines 107-143) correctly handles errors in its catch block, but this code path does not.

Proposed fix

     if (isDesktopVersionInitialized() && !serverData) {
       getDesktopVersionData().then((versionData) => {
         if (isMounted) {
           setData({
             latest: versionData.latest,
             platforms: versionData.platforms,
             error: versionData.error,
             loading: false,
             stable: {
               latest: versionData.channels.stable.latest,
               all: versionData.channels.stable.all,
             },
             beta: {
               latest: versionData.channels.beta.latest,
               all: versionData.channels.beta.all,
             },
           });
         }
+      }).catch((error) => {
+        if (isMounted) {
+          setData({
+            latest: null,
+            platforms: [],
+            error: error instanceof Error ? error.message : 'Unknown error',
+            loading: false,
+            stable: { latest: null, all: [] },
+            beta: { latest: null, all: [] },
+          });
+        }
       });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@shared/src/desktop-context.tsx` around lines 147 - 165, The promise returned
by getDesktopVersionData() inside the isDesktopVersionInitialized() branch is
not handled for rejection; add a .catch() (or use async/await with try/catch) to
that chain so any error sets state like the loadData() catch block does: call
setData(...) to set loading:false and populate the error field (and sensible
defaults for latest/platforms/stable/beta) when getDesktopVersionData() rejects,
ensuring you only call setData when isMounted is true; reference
getDesktopVersionData, isDesktopVersionInitialized, setData, and mirror the
error handling in loadData.

astro.config.mjs-56-59 (1)

56-59: ⚠️ Potential issue | 🟠 Major

Overriding import.meta.env.PROD may conflict with Astro/Vite defaults.

Astro and Vite already define import.meta.env.PROD based on the build mode (--mode production). Redefining it via vite.define to depend on process.env.NODE_ENV could cause mismatches — for example, astro build sets PROD=true regardless of NODE_ENV, but this override would set it to false if NODE_ENV isn't explicitly "production".

Consider removing this override and letting Astro/Vite manage PROD natively.

Proposed fix

     define: {
-      'import.meta.env.PROD': JSON.stringify(
-        process.env.NODE_ENV === 'production'
-      ),
       "import.meta.env.VITE_CLARITY_PROJECT_ID": JSON.stringify(

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@astro.config.mjs` around lines 56 - 59, The config currently overrides
'import.meta.env.PROD' via the define block (the define object setting
'import.meta.env.PROD'), which can conflict with Astro/Vite's built-in mode
handling; remove the explicit definition of 'import.meta.env.PROD' from the
define object in astro.config.mjs so that Astro/Vite control PROD based on the
build mode (or if you need a custom flag, use a different key like
VITE_CUSTOM_PROD and reference that instead).

src/components/StarlightHeader.astro-33-48 (1)

33-48: ⚠️ Potential issue | 🟠 Major

Mobile navigation gap: custom nav links and InstallButton inaccessible below 64rem.

The custom nav links and InstallButton are hidden below 64rem (line 164), while .right-group uses md:sl-flex (~50rem). Between these breakpoints, the right group is visible but nav links are hidden. More critically, these custom nav items are not integrated into Starlight's default sidebar or mobile menu—they exist only in StarlightHeader and have no fallback on small screens. Users below 64rem cannot access the InstallButton or the three custom navigation links (首页, 博客, 技术支持群) anywhere else in the interface.

Either expose these nav items in a mobile menu, or integrate them into Starlight's sidebar navigation.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/components/StarlightHeader.astro` around lines 33 - 48, The right-group
in StarlightHeader currently uses md:sl-flex so its container remains visible at
~50rem while the nav links use classes that hide them below 64rem, leaving
InstallButton and navLinks inaccessible on many small screens; fix by either (A)
moving or duplicating the navLinks and InstallButton into Starlight's
sidebar/mobile menu API so they appear in the built-in mobile drawer (export or
pass navLinks into the app/sidebar nav config used by Starlight), or (B) change
the visibility classes on the <nav class="custom-nav-links"> and InstallButton
so they become visible at the same breakpoint as .right-group (e.g., replace
high-breakpoint hide classes with sl:flex or the matching sl-visible utility),
and ensure external link props (link.external) and <Icon /> rendering remain
unchanged; update StarlightHeader's navLinks usage and InstallButton placement
accordingly so mobile users can access 首页, 博客, and 技术支持群.

shared/src/version-manager.ts-145-166 (1)

145-166: ⚠️ Potential issue | 🟠 Major

Failed fetches are retried on every subsequent call with no backoff.

When fetchDesktopVersions() throws (line 145), the error path rejects pending promises and re-throws, but never sets this.initialized or this.data. The next call to getVersionData() will bypass all caches and attempt another fetch immediately. Under persistent network failures, every component mount triggers a new failing request — potentially causing request storms.

Consider caching the error state (with a TTL) so that callers within a cooldown window get the cached error instead of triggering another fetch:

🛡️ Sketch of error caching with TTL

+  private lastErrorTime: number = 0;
+  private static ERROR_RETRY_MS = 30_000; // 30s cooldown
+
   async getVersionData(): Promise<DesktopVersionData> {
     if (this.initialized && this.data) {
       return this.data;
     }
+
+    // Return cached error within cooldown window
+    if (this.data?.error && Date.now() - this.lastErrorTime < VersionManager.ERROR_RETRY_MS) {
+      throw new Error(this.data.error);
+    }
     // ... existing fetch logic ...
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
       const errorData: DesktopVersionData = { /* ... */ };
+      this.data = errorData;
+      this.lastErrorTime = Date.now();
       // ...

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@shared/src/version-manager.ts` around lines 145 - 166, When
fetchDesktopVersions() fails, record and cache the error state so subsequent
getVersionData() calls within a short TTL return the cached error instead of
triggering immediate refetches: build an error DesktopVersionData (as in your
errorData variable), assign it to this.data and set this.initialized = true,
store a timestamp like this.dataErrorTimestamp (or similar), clear
pendingPromises as you already do, and rethrow; then update getVersionData() to
check if initialized and whether data contains an error whose timestamp is
younger than the TTL—if so, return the cached error data immediately; ensure
this.fetching is still set correctly in finally and that successful fetches
clear the error timestamp.

shared/src/version.ts-192-201 (1)

192-201: ⚠️ Potential issue | 🟠 Major

semver.compare throws on invalid version strings — add defensive handling.

semver.compare(cleaned1, cleaned2) throws a TypeError if either argument is not a valid semver. Since compareVersions is called inside a .reduce() in getLatestVersionFromVersions, malformed version entries will crash the reduction. While the exception is caught by the outer try/catch in getLatestVersion, the error handling is implicit and fragile.

Validate versions using semver.coerce() before comparing, consistent with the approach used in scripts/version-monitor.js:

🛡️ Proposed fix

 export function compareVersions(v1: string, v2: string): number {
   const cleaned1 = v1.replace(/^v/, '');
   const cleaned2 = v2.replace(/^v/, '');
 
-  const cmp = semver.compare(cleaned1, cleaned2);
-  // semver.compare returns: negative if a < b, 0 if equal, positive if a > b
-  if (cmp < 0) return -1;
-  if (cmp > 0) return 1;
-  return 0;
+  // coerce handles partial versions like "1.2" or "1" gracefully
+  const sv1 = semver.coerce(cleaned1);
+  const sv2 = semver.coerce(cleaned2);
+
+  if (!sv1 && !sv2) return 0;
+  if (!sv1) return -1;
+  if (!sv2) return 1;
+
+  return semver.compare(sv1.version, sv2.version);
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@shared/src/version.ts` around lines 192 - 201, compareVersions currently
calls semver.compare directly and will throw if inputs are invalid; update
compareVersions to coerce both inputs first (use semver.coerce on cleaned1 and
cleaned2), then: if both coerced are null return 0, if only one coerces treat
the valid one as greater (return 1 if v1 coerced and v2 not, -1 if v2 coerced
and v1 not), otherwise call semver.compare on the coerced.version strings and
map to -1/0/1 as before; this keeps compareVersions (used by
getLatestVersionFromVersions/getLatestVersion) defensive against malformed
version strings.